home *** CD-ROM | disk | FTP | other *** search
/ SGI Freeware 2002 November / SGI Freeware 2002 November - Disc 1.iso / dist / fw_apache2.idb / usr / freeware / apache2 / include / apr_hooks.h.z / apr_hooks.h
C/C++ Source or Header  |  2002-07-08  |  10KB  |  287 lines
  1. /* ====================================================================
  2.  * The Apache Software License, Version 1.1
  3.  *
  4.  * Copyright (c) 2000-2002 The Apache Software Foundation.  All rights
  5.  * reserved.
  6.  *
  7.  * Redistribution and use in source and binary forms, with or without
  8.  * modification, are permitted provided that the following conditions
  9.  * are met:
  10.  *
  11.  * 1. Redistributions of source code must retain the above copyright
  12.  *    notice, this list of conditions and the following disclaimer.
  13.  *
  14.  * 2. Redistributions in binary form must reproduce the above copyright
  15.  *    notice, this list of conditions and the following disclaimer in
  16.  *    the documentation and/or other materials provided with the
  17.  *    distribution.
  18.  *
  19.  * 3. The end-user documentation included with the redistribution,
  20.  *    if any, must include the following acknowledgment:
  21.  *       "This product includes software developed by the
  22.  *        Apache Software Foundation (http://www.apache.org/)."
  23.  *    Alternately, this acknowledgment may appear in the software itself,
  24.  *    if and wherever such third-party acknowledgments normally appear.
  25.  *
  26.  * 4. The names "Apache" and "Apache Software Foundation" must
  27.  *    not be used to endorse or promote products derived from this
  28.  *    software without prior written permission. For written
  29.  *    permission, please contact apache@apache.org.
  30.  *
  31.  * 5. Products derived from this software may not be called "Apache",
  32.  *    nor may "Apache" appear in their name, without prior written
  33.  *    permission of the Apache Software Foundation.
  34.  *
  35.  * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
  36.  * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
  37.  * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
  38.  * DISCLAIMED.  IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR
  39.  * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  40.  * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  41.  * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
  42.  * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
  43.  * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
  44.  * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
  45.  * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  46.  * SUCH DAMAGE.
  47.  * ====================================================================
  48.  *
  49.  * This software consists of voluntary contributions made by many
  50.  * individuals on behalf of the Apache Software Foundation.  For more
  51.  * information on the Apache Software Foundation, please see
  52.  * <http://www.apache.org/>.
  53.  */
  54.  
  55. #ifndef APR_HOOKS_H
  56. #define APR_HOOKS_H
  57.  
  58. #include "apu.h"
  59. /* For apr_array_header_t */
  60. #include "apr_tables.h"
  61.  
  62. /**
  63.  * @file apr_hooks.h
  64.  * @brief Apache hook functions
  65.  */
  66.  
  67. #ifdef __cplusplus
  68. extern "C" {
  69. #endif
  70. /**
  71.  * @defgroup APR_Util_Hook Hook Functions
  72.  * @ingroup APR_Util
  73.  * @{
  74.  */
  75. /** macro to return the prototype of the hook function */    
  76. #define APR_IMPLEMENT_HOOK_GET_PROTO(ns,link,name) \
  77. link##_DECLARE(apr_array_header_t *) ns##_hook_get_##name(void)
  78.  
  79. /** macro to declare the hook correctly */    
  80. #define APR_DECLARE_EXTERNAL_HOOK(ns,link,ret,name,args) \
  81. typedef ret ns##_HOOK_##name##_t args; \
  82. link##_DECLARE(void) ns##_hook_##name(ns##_HOOK_##name##_t *pf, \
  83.                                       const char * const *aszPre, \
  84.                                       const char * const *aszSucc, int nOrder); \
  85. link##_DECLARE(ret) ns##_run_##name args; \
  86. APR_IMPLEMENT_HOOK_GET_PROTO(ns,link,name); \
  87. typedef struct ns##_LINK_##name##_t \
  88.     { \
  89.     ns##_HOOK_##name##_t *pFunc; \
  90.     const char *szName; \
  91.     const char * const *aszPredecessors; \
  92.     const char * const *aszSuccessors; \
  93.     int nOrder; \
  94.     } ns##_LINK_##name##_t;
  95.  
  96. /** macro to declare the hook structure */    
  97. #define APR_HOOK_STRUCT(members) \
  98. static struct { members } _hooks;
  99.  
  100. #define APR_HOOK_LINK(name) \
  101.     apr_array_header_t *link_##name;
  102.  
  103. #define APR_IMPLEMENT_EXTERNAL_HOOK_BASE(ns,link,name) \
  104. link##_DECLARE(void) ns##_hook_##name(ns##_HOOK_##name##_t *pf,const char * const *aszPre, \
  105.                                       const char * const *aszSucc,int nOrder) \
  106.     { \
  107.     ns##_LINK_##name##_t *pHook; \
  108.     if(!_hooks.link_##name) \
  109.     { \
  110.     _hooks.link_##name=apr_array_make(apr_global_hook_pool,1,sizeof(ns##_LINK_##name##_t)); \
  111.     apr_hook_sort_register(#name,&_hooks.link_##name); \
  112.     } \
  113.     pHook=apr_array_push(_hooks.link_##name); \
  114.     pHook->pFunc=pf; \
  115.     pHook->aszPredecessors=aszPre; \
  116.     pHook->aszSuccessors=aszSucc; \
  117.     pHook->nOrder=nOrder; \
  118.     pHook->szName=apr_current_hooking_module; \
  119.     if(apr_debug_module_hooks) \
  120.     apr_show_hook(#name,aszPre,aszSucc); \
  121.     } \
  122.     APR_IMPLEMENT_HOOK_GET_PROTO(ns,link,name) \
  123.     { \
  124.         return _hooks.link_##name; \
  125.     }
  126.  
  127. /**
  128.  * Implement a hook that has no return code, and therefore runs all of the
  129.  * registered functions
  130.  * @param ns The namespace prefix of the hook functions
  131.  * @param link The linkage declaration prefix of the hook
  132.  * @param name The name of the hook
  133.  * @param args_decl The declaration of the arguments for the hook
  134.  * @param args_used The names for the arguments for the hook
  135.  * @note The link prefix FOO corresponds to FOO_DECLARE() macros, which
  136.  * provide export linkage from the module that IMPLEMENTs the hook, and
  137.  * import linkage from external modules that link to the hook's module.
  138.  */
  139. #define APR_IMPLEMENT_EXTERNAL_HOOK_VOID(ns,link,name,args_decl,args_use) \
  140. APR_IMPLEMENT_EXTERNAL_HOOK_BASE(ns,link,name) \
  141. link##_DECLARE(void) ns##_run_##name args_decl \
  142.     { \
  143.     ns##_LINK_##name##_t *pHook; \
  144.     int n; \
  145. \
  146.     if(!_hooks.link_##name) \
  147.     return; \
  148. \
  149.     pHook=(ns##_LINK_##name##_t *)_hooks.link_##name->elts; \
  150.     for(n=0 ; n < _hooks.link_##name->nelts ; ++n) \
  151.     pHook[n].pFunc args_use; \
  152.     }
  153.  
  154. /* FIXME: note that this returns ok when nothing is run. I suspect it should
  155.    really return decline, but that breaks Apache currently - Ben
  156. */
  157. /**
  158.  * Implement a hook that runs until one of the functions returns something
  159.  * other than OK or DECLINE
  160.  * @param ns The namespace prefix of the hook functions
  161.  * @param link The linkage declaration prefix of the hook
  162.  * @param name The name of the hook
  163.  * @param args_decl The declaration of the arguments for the hook
  164.  * @param args_used The names for the arguments for the hook
  165.  * @note The link prefix FOO corresponds to FOO_DECLARE() macros, which
  166.  * provide export linkage from the module that IMPLEMENTs the hook, and
  167.  * import linkage from external modules that link to the hook's module.
  168.  */
  169. #define APR_IMPLEMENT_EXTERNAL_HOOK_RUN_ALL(ns,link,ret,name,args_decl,args_use,ok,decline) \
  170. APR_IMPLEMENT_EXTERNAL_HOOK_BASE(ns,link,name) \
  171. link##_DECLARE(ret) ns##_run_##name args_decl \
  172.     { \
  173.     ns##_LINK_##name##_t *pHook; \
  174.     int n; \
  175.     ret rv; \
  176. \
  177.     if(!_hooks.link_##name) \
  178.     return ok; \
  179. \
  180.     pHook=(ns##_LINK_##name##_t *)_hooks.link_##name->elts; \
  181.     for(n=0 ; n < _hooks.link_##name->nelts ; ++n) \
  182.     { \
  183.     rv=pHook[n].pFunc args_use; \
  184. \
  185.     if(rv != ok && rv != decline) \
  186.         return rv; \
  187.     } \
  188.     return ok; \
  189.     }
  190.  
  191.  
  192. /**
  193.  * Implement a hook that runs until the first function returns something
  194.  * other than the value of decline
  195.  * @param ns The namespace prefix of the hook functions
  196.  * @param link The linkage declaration prefix of the hook
  197.  * @param name The name of the hook
  198.  * @param args_decl The declaration of the arguments for the hook
  199.  * @param args_used The names for the arguments for the hook
  200.  * @note The link prefix FOO corresponds to FOO_DECLARE() macros, which
  201.  * provide export linkage from the module that IMPLEMENTs the hook, and
  202.  * import linkage from external modules that link to the hook's module.
  203.  */
  204. #define APR_IMPLEMENT_EXTERNAL_HOOK_RUN_FIRST(ns,link,ret,name,args_decl,args_use,decline) \
  205. APR_IMPLEMENT_EXTERNAL_HOOK_BASE(ns,link,name) \
  206. link##_DECLARE(ret) ns##_run_##name args_decl \
  207.     { \
  208.     ns##_LINK_##name##_t *pHook; \
  209.     int n; \
  210.     ret rv; \
  211. \
  212.     if(!_hooks.link_##name) \
  213.     return decline; \
  214. \
  215.     pHook=(ns##_LINK_##name##_t *)_hooks.link_##name->elts; \
  216.     for(n=0 ; n < _hooks.link_##name->nelts ; ++n) \
  217.     { \
  218.     rv=pHook[n].pFunc args_use; \
  219. \
  220.     if(rv != decline) \
  221.         return rv; \
  222.     } \
  223.     return decline; \
  224.     }
  225.  
  226.     /* Hook orderings */
  227. /** run this hook first, before ANYTHING */
  228. #define APR_HOOK_REALLY_FIRST    (-10)
  229. /** run this hook first */
  230. #define APR_HOOK_FIRST        0
  231. /** run this hook somewhere */
  232. #define APR_HOOK_MIDDLE        10
  233. /** run this hook after every other hook which is defined*/
  234. #define APR_HOOK_LAST        20
  235. /** run this hook last, after EVERYTHING */
  236. #define APR_HOOK_REALLY_LAST    30
  237.  
  238. /**
  239.  * The global pool used to allocate any memory needed by the hooks.
  240.  */ 
  241. APU_DECLARE_DATA extern apr_pool_t *apr_global_hook_pool;
  242.  
  243. /**
  244.  * A global variable to determine if debugging information about the
  245.  * hooks functions should be printed
  246.  */ 
  247. APU_DECLARE_DATA extern int apr_debug_module_hooks;
  248.  
  249. /**
  250.  * The name of the module that is currently registering a function
  251.  */ 
  252. APU_DECLARE_DATA extern const char *apr_current_hooking_module;
  253.  
  254. /**
  255.  * Register a hook function to be sorted
  256.  * @param szHookName The name of the Hook the function is registered for
  257.  * @param aHooks The array which stores all of the functions for this hook
  258.  */
  259. APU_DECLARE(void) apr_hook_sort_register(const char *szHookName, 
  260.                                         apr_array_header_t **aHooks);
  261. /**
  262.  * Sort all of the registerd functions for a given hook
  263.  */
  264. APU_DECLARE(void) apr_sort_hooks(void);
  265.  
  266. /**
  267.  * Print all of the information about the current hook.  This is used for
  268.  * debugging purposes.
  269.  * @param szName The name of the hook
  270.  * @param aszPre All of the functions in the predecessor array
  271.  * @param aszSucc All of the functions in the successor array
  272.  */
  273. APU_DECLARE(void) apr_show_hook(const char *szName,const char * const *aszPre,
  274.                                const char * const *aszSucc);
  275.  
  276. /**
  277.  * Remove all currently registered functions.
  278.  */
  279. APU_DECLARE(void) apr_hook_deregister_all(void);
  280.  
  281. /** @} */
  282. #ifdef __cplusplus
  283. }
  284. #endif
  285.  
  286. #endif /* APR_HOOKS_H */
  287.